home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / e / lsthndln.lha / listhandling.doc next >
Text File  |  1995-11-09  |  5KB  |  192 lines
  1. listhandling.m module  v1.0 - by Eric Sauvageau.
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Released to the Public Domain on November 10th, 1995.
  5.  
  6.  
  7. This is a small Amiga E module I originally created for my own projects.  
  8. These functions are meant to ease the use and handling of Exec's linked 
  9. lists, such as those used in ListView gadgets.  
  10.  
  11. The module should work with any Kickstart version, although it only has 
  12. been tested under 2.04 and up.  It requires at least EC 3.0a to be used.
  13.  
  14.  
  15. Exceptions:
  16. ~~~~~~~~~~~
  17. Functions failing because of low memory will raise the exception "MEM".
  18.  
  19.  
  20.  
  21. Functions:
  22. ~~~~~~~~~~
  23.  
  24. list := lh_newList()
  25. --------------------
  26.  
  27. DESCRIPTION: 
  28.    Will initialize a standard Exec linked list.
  29.  
  30. INPUTS: 
  31.    None.
  32.  
  33. RETURN: 
  34.    A pointer to the new list.
  35.  
  36. EXAMPLE: 
  37.    driveList := lh_newList()
  38.  
  39.  
  40.  
  41.  
  42. node := lh_newnode(name,size)
  43. -----------------------------
  44.  
  45. DESCRIPTION:
  46.   Create a new Exec listnode.
  47.  
  48. INPUTS:
  49.    "name" is a STRING holding the name of the new node.
  50.    "size" is the size of the node.  For standard Exec listnodes, use 
  51.           "SIZEOF ln".
  52.  
  53. RETURN:
  54.    A pointer to the new node, of "ln" type.
  55.  
  56. EXAMPLE:   
  57.    node := lh_newnode('DF0:',(SIZEOF ln))
  58.  
  59.  
  60.  
  61.  
  62. position := lh_addNodeSorted(list,node)
  63. ---------------------------------------
  64.  
  65. DESCRIPTION:
  66.   Add a listnode to a list.  The nodes will be kept sorted by alphabetical 
  67.   order (NON-case sensitive!).  Duplicate nodes won't be added.
  68.  
  69. INPUTS:
  70.   "list" is the Exec list.
  71.   "node" is the listnode to be added.
  72.  
  73. RETURN:
  74.   The position in the list where the node has been added, or -1 if the node 
  75.   wasn't added for some reason (already existing or error).
  76.  
  77. EXAMPLE:
  78.   position := lh_addNodeSorted(myList, someNode)
  79.   IF position = -1 THEN WriteF('Couldn''t add node \s!\n',someNode.name)
  80.  
  81.  
  82.  
  83. lh_freeList(list, deallocate=FALSE)
  84. -----------------------------------
  85.  
  86. DESCRIPTION:
  87.   Will remove every nodes linked to a given list, and free the memory 
  88.   associated with them.  Can also deallocate the list itself if needed.
  89.  
  90. INPUTS:
  91.   "list" is the Exec list from which all nodes will be removed and freed.
  92.  
  93.   "deallocate" is a boolean value.  If "TRUE". the list structure itself 
  94.   will be deallocated.
  95.  
  96. NOTES:
  97.   The nodes must be standard Exec ln structures!  Or, at least, they 
  98.   must not have anything else than LONG values.  What I mean: the procedure 
  99.   will free the memory allocated for node.name (which is a STRING ptr ), and 
  100.   then the node structure itself.  If some elements of your nodes are 
  101.   PTR TO a memory area which needs specific de-allocation, this memory 
  102.   will be lost (unless you're using an E memory allocation call, in which 
  103.   case memory will be freed when the program is exited).
  104.  
  105.  
  106. EXAMPLE:
  107.   lh_freeList(myList,TRUE)
  108.  
  109.  
  110.  
  111.  
  112. position := lh_getPosition(list,name)
  113. -------------------------------------
  114.  
  115. DESCRIPTION:
  116.   Returns the position in a list of the node named "name".
  117.   Usefull when you want to know what's the position of an item in a 
  118.   ListView gadget, as example.
  119.  
  120. INPUTS:
  121.   "list" is an Exec list.
  122.   "name" is a STRING with the name of the node to be located.
  123.  
  124. RETURN:
  125.   The position of the "name" node in the list, or "-1" if the node couldn't 
  126.   be found.
  127.  
  128. EXAMPLE:
  129.   IF (lh_getPosition(myList,'MONEY') THEN WriteF('Can''t find "MONEY"!\n')
  130.  
  131.  
  132.  
  133.  
  134. node := lh_getNode(list,position)
  135. ---------------------------------
  136.  
  137. DESCRIPTION:
  138.   Returns a pointer to the "x"th node in the list.
  139.  
  140. INPUTS:
  141.   "list" is an Exec list.
  142.   "position" is the position of the desired node.
  143.  
  144. RETURNS:
  145.   A pointer to the node found at the specified position in the list.
  146.  
  147. EXAMPLE:
  148.   myNode := lh_getNode(myList, 3)
  149.  
  150.  
  151.  
  152.  
  153. total := lh_itemsTotal(list)
  154. ----------------------------
  155.  
  156. DESCRIPTION:
  157.   Returns the number of nodes linked to the specified list.
  158.  
  159. INPUTS:
  160.   "list" is an Exec list.
  161.  
  162. RETURN:
  163.   The number of nodes linked to "list".
  164.  
  165.  
  166.  
  167.  
  168. Additional informations
  169. ~~~~~~~~~~~~~~~~~~~~~~~
  170. I make no guaranties that this module is bug-free or will work as 
  171. expected.   I'm releasing it as a way to say "Thanks guys!" to the other 
  172. Amiga E programmers who released source code examples to the Public Domain, 
  173. which have often been VERY usefull to me.
  174.  
  175. Feel free to use this code in your own programs and to modify it if 
  176. something doesn't satisfy you.  I just ask you to NOT release modified 
  177. versions of the module without at least asking me first.  This way, we'll 
  178. avoid any mess if I decide to released an updated version at a later time 
  179. and someone already released his OWN update.
  180.  
  181.  
  182. If you wish to reach me, you can Email me at:
  183.  
  184. Fidonet:  Eric Sauvageau @ 1:242/907.0
  185.  
  186. Internet: dream@step.polymtl.ca  (this account belongs to a friend.  Try 
  187.           the Fidonet address if there's no reply after a few days.  As 
  188.           soon the local Freenet will be up, I'll have my own address :)
  189.  
  190. I can also be found on #amiga on EffNet under the nick "RMerlin".
  191.  
  192.